Release 10.1A: OpenEdge Development:
ProDataSets

COPY-DATASET and COPY-TEMP-TABLE methods

So far this example has shown you how to append additional data to a single ProDataSet, and to control which parts of it get filled in at different times. In this section, you’ll learn about two additional Progress 4GL methods that can assist you when you need to copy or combine data in other ways.

The COPY-DATASET method copies all the data in one ProDataSet to another. For example:

Syntax

target-dataset-handle:COPY-DATASET(source-dataset-handle [ , append-mode ] ).

The source-dataset-handle must be the handle of an existing static or dynamic ProDataSet. The target-dataset-handle can be the handle of another static or dynamic ProDataSet with the same temp-table and Data-Relation structure. It can also be a newly created dynamic ProDataSet with only a handle and no structure, that is, the result of executing the statement CREATE DATASET target-dataset-handle. If the target-dataset has no structure, the table and Data-Relation structure of the source-dataset is copied to it along with the data. In this case the dynamic target ProDataSet is not given a name, but its temp-tables and their buffers are given the name “cpy_” plus the name of the temp-table or buffer in the source ProDataSet.

COPY-DATASET copies the temp-tables from source to target in the order that they were defined or added in the two ProDataSets. As soon as it encounters a pair that do not have compatible table definitions, it puts out an error message and terminates the operation. As with other operations, two temp-table definitions are considered compatible if they contain the same number of fields with matching datatypes and extents for each field. Whether the field names are identical in the two tables does not matter. If either the source or target ProDataSet has an extra temp-table or temp-tables at the end of the ProDataSet, the COPY-DATASET succeeds because the unpaired tables are ignored.

By default, the tables in the target ProDataSet are emptied at the start of the COPY-DATASET operation, so that the end result is that the target ProDataSet temp-tables have the same rows as in the source ProDataSet. If you instead want to merge the data in the two ProDataSets, you include the optional second merge-flag parameter on the method call. If this logical parameter is present and evaluates to true, then data from the source ProDataSet temp-tables is merged into the target temp-tables according to the rules of the “MERGE” value for a temp-table buffer’s FILL-MODE during a FILL. That is, rows from the two corresponding tables in each pair are combined so that the target ends up with all the rows that were in either the source or target at the start. If there is a unique index on the target temp-table, all rows from the source that violate that index constraint are silently eliminated during the COPY-DATASET operation, so that the target winds up with only one row for each index value. Note that there is no interleaving of data in related tables as it is copied from the source ProDataSet to the target. Each temp-table is copied individually in its entirety, starting at the top of the ProDataSet hierarchy. If duplicate rows are eliminated from a parent table in the course of the copy, this has no effect on the related rows in any child table.

If the source ProDataSet has any before-tables that have any rows in them, you cannot use COPY-DATASET on that ProDataSet. It would not be appropriate to copy and duplicate this transactional data, which is presumably waiting to be committed back to its Data-Source. Since it would also not be appropriate to copy the ProDataSet and silently omit this data, it’s simply not allowed. If you need to copy after-tables from one ProDataSet to another at a time when the before-tables have data in them, you can use the COPY-TEMP-TABLE method.

COPY-DATASET has four additional positional, optional arguments. The replace-mode, loose-copy-mode and current-only options are LOGICAL datatypes, and the pairs-list option is a character expression. The full syntax of COPY-DATASET is. For example:

Syntax

target-dataset-handle:COPY-DATASET(source-dataset-handle [ , append-mode ] [ , replace-mode ] [ , loose-copy-mode ] [ , pairs-list ] [ , current-only]).

The COPY-TEMP-TABLE method works similarly for individual temp-tables, as shown:

Syntax

target-table-handle:COPY-TEMP-TABLE(source-table-handle [ , append-mode ] [ , replace-mode ] [ , loose-copy-mode ] ).

You can use the COPY-TEMP-TABLE method on any source or target temp-table, whether it is part of a ProDataSet or not. Therefore you can use this method to copy individual temp-tables from one ProDataSet to another, or for other temp-tables having nothing to do with ProDataSets.

As with COPY-DATASET, by default the target temp-table is emptied at the start of the operation. The rules for temp-table compatibility, the use of the optional merge-flag, and so on, are the same as for COPY-DATASET.

The replace-mode argument

The replace-mode option defaults to FALSE. If replace-mode is TRUE, Progress tries to find the corresponding row in the target table, through the target’s unique primary index. If a corresponding row is not found in the target table, Progress uses the source row to create a new target row. If Progress finds the row in the target, it copies the source row values into that row. If the target row has a BEFORE-TABLE row, that row is left in place. There must be a unique primary index on each target member table in order for the replace-mode option to be used.

When replace-mode is TRUE, it does not matter if append-mode is TRUE or FALSE. The target table is not emptied prior to the copy operation.

The loose-copy-mode argument

By default, pairs of source and target temp-tables being copied by the COPY-DATASET or COPY-TEMP-TABLE method must have compatible definitions. The loose-copy-mode option overrides this default.

For the COPY-DATASET method, if loose-copy-mode is TRUE, the parameter applies to each temp-table buffer in the ProDataSet. Thus, the remainder of this paragraph applies to both the COPY-DATASET and COPY-TEMP-TABLE methods. If loose-copy-mode is TRUE for a temp-table buffer, Progress effectively performs a BUFFER-COPY from source to target. BUFFER-COPY is more flexible than the default behavior of COPY-TEMP-TABLE or COPY-DATASET because it matches each source field to its corresponding field in the target by name, and ignores fields that do not match, without error. This is somewhat more expensive than the default behavior of COPY-DATASET and COPY-TEMP-TABLE, which assumes compatible definitions field-for-field between source and target. When loose-copy-mode is TRUE, Progress checks for an existing field-mapping between the two buffers specified in a previous ATTACH-DATA-SOURCE operation. If the source temp-table is in fact the Data-Source for the target, then its field-mapping is used to match up field pairs with differing names, just as for BUFFER-COPY. If there is no ATTACH-DATA-SOURCE between the two buffers, the copy is done by matching field names and only copying those fields that appear in both source and target. As with BUFFER-COPY, different field order and missing fields do not prevent the method from succeeding. There is also no requirement that indexes on the two temp-tables be identical.

The pairs-list argument

The pairs-list argument only applies to COPY-DATASET. The pairs-list is a comma-separated list of target and source tables to be copied, such as: targetT1,sourceT1,targetT2,sourceT2. If the pairs-list is present, the copy is done between only those member tables given in the pairs-list, by matching target and source table names. If the pairs-list is not given, the tables are copied in the order in which they were defined or added in the two ProDataSets.

If one ProDataSet has more tables than the other, the extra unpaired tables are ignored. In other words, you can use COPY-DATASET without the pairs-list option to copy one ProDataSet to another, even when one ProDataSet has more tables than the other, as long as the tables to be copied have the same relative positions within the ProDataSet structure. This is the same as the order in which the tables would be returned by the GET-BUFFER-HANDLE (i) method.

If the tables to be copied are not in the same relative order, then you must specify the pairs-list option to tell Progress which source tables go with which targets. If the source and target tables don’t match up in their relative order within their respective ProDataSets, you must specify the pairs-list even if the table names are the same.

For example, given a source ProDataSet with temp-tables T1, T2, and T3, and a target ProDataSet with just tables T1 and T3, you must define the pairs-list option to be T1,T1,T3,T3, because the relative position of T3 in the two ProDataSets is not the same, even though the table names are the same. It is also worth noting that for static temp-table definitions, it is not possible for the source and target temp-tables to have the same name anyway, since each static name defines a single unique instance with that name.

The current-only argument

The current-only argument also applies only to COPY-DATASET. If current-only is present and is TRUE, it tells Progress to copy only the current buffer contents of each source ProDataSet buffer to the target ProDataSet. This option can be useful in situations where the business logic needs to deal with a modified row and its parent (and possibly grand-parent, etc.) without using any other rows. The current-only option is a way of getting this minimal set of data to pass to such an operation. Note that you might need to set the AUTO-SYNCHRONIZE attribute to TRUE or execute the SYNCHRONIZE( ) method to ensure that the contents of each buffer are what is needed. Since the usefulness of the current-only option is that it automatically copies a single row at multiple levels at once, it is supported only for COPY-DATASET. For a temp-table, you can use a single BUFFER-COPY statement or method to copy a single row.